refactor(contracts): name façade exports explicitly and retire the pin table - #1614

Size Report

Startup median (7 runs, lower is better):

Top changed chunks: no changes in the largest emitted chunks.

P1 — rebase this conversion onto current main and regenerate the explicit façade lists from that public surface before deleting facade-symbols.ts.

#1567 landed after this branch forked and added 13 exports that the existing export * façades forwarded: DragOptions in contracts/client; the drag gesture values/types/helpers in contracts/interaction (COORDINATE_GESTURE_KINDS, CoordinateGesturePayload, the three DEFAULT_DRAG_* constants, DragGestureInput, DragGesturePayload, GestureCommandInput, buildDragGesturePlan, dragGesturePayloadFromPositionals, and normalizeGestureCommandInput); and MultiTargetAnnotationV1 in contracts/replay. None appears in this head’s explicit lists.

The #1567 update to facade-symbols.ts is now a modify/delete conflict with this PR. Resolving it by deleting the table while retaining these lists removes those public symbols; it also breaks current in-repo imports, including MultiTargetAnnotationV1 from @agent-device/contracts/replay. The replacement structural gate only rejects bare stars, so it will not catch this narrowed surface. Please carry all 13 exports into the rebase resolution and validate the resulting surface before retiring the table.

Separately, the iOS Smoke job is red on RunnerTests.testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden ("h" vs "hardware-keyboard"). This refactor does not touch that runner path, so it is unrelated to the P1 above, but it remains an owner-action CI failure that needs a rerun or diagnosis before merge.

Follow-up on the earlier P1: the rebase correctly restores the 13 exports added by #1567. I independently compared every contracts subpath against current main’s resolved star surfaces: all 15 match exactly, and the branch is now mergeable.

Two blockers remain:

• P1 — Fallow is a real owner-action failure, not a flake. Fallow Code Quality reports the three new public re-exports at packages/contracts/src/facades/interaction.ts:41-43 as unused: DEFAULT_DRAG_DESTINATION_HOLD_MS, DEFAULT_DRAG_MOVE_MS, and DEFAULT_DRAG_SOURCE_HOLD_MS. The existing public-façade suppression preserves the other intentional contract exports but omits these three. Add them there (or establish production consumers) and rerun the gate.

• P2 — the new exhaustiveness regression gate is incomplete for gesture-plan.ts. When readNamedExports hits that source’s bare export *, the test catches the error and continues, skipping that module’s direct exports too. The façade separately names gesture-plan-types, so the transitive type star is covered, but a future direct gesture-plan.ts export — for example removing buildDragGesturePlan alone from the façade — would silently narrow the public surface and still pass this test. Make that source enumerable or have the gate check its direct exports while resolving/handling the star separately.

Both blockers addressed on 5196cf7, plus a third the new gate caught on itself.

P1 — suppression extended. The three DEFAULT_DRAG_* constants join the existing public-façade entry, together with COORDINATE_GESTURE_KINDS and normalizePublicGesture which the same conversion surfaced for the same reason. check:production-exports is green. The rationale comment now names them as #1567's drag vocabulary explicitly.

P2 — real hole, fixed. You were right that continue dropped the starred module's direct exports from the check. readDirectNamedExports now reads exactly what a module declares or re-exports by name and ignores the star; the starred set stays covered because the façade re-exports the starred module directly too, and that path is checked on its own turn.

Red evidence: removing buildDragGesturePlan from facades/interaction.ts now fails with file, source and symbol named — it passed silently before. 13 pass / 0 fail restored. (My first attempt to plant this used a sed that didn't match the multi-line list and reported a false green; worth knowing if you reproduce it.)

Third — the gate paid for itself during this fix. Rebasing onto main after #1612 merged silently dropped TEXT_ENTRY_ROUTES, TextEntryRoute and TypeTextBackendResult from the interaction façade. Same narrowing class as the #1567 one you caught by hand, one merge later, and the gate failed on it before CI did. Restored.

That is twice now that this conversion has narrowed the surface on a rebase, which I think settles whether the gate earns its keep.

Gates: typecheck / lint / format / check:layering / check:production-exports / check:fallow all green.

🤖 Addressed by Claude Code

Re-reviewed exact head 5196cf7cb11756bc03c6e4a614e23eeddd081076: clean and ready for human review.

The prior findings are resolved: all three DEFAULT_DRAG_* exports have the scoped Fallow treatment, and the façade-exhaustiveness gate now retains direct named exports from sources that also carry export *, covering buildDragGesturePlan. Public contract-façade surface parity remains exact, including the restored #1612 text-entry exports (TEXT_ENTRY_ROUTES, TextEntryRoute, and TypeTextBackendResult).

The structural gates and all GitHub checks are green. This is a surface-preserving structural refactor, so runtime/device evidence is not required. No blockers found.